Disclaimer: Although LDapper seems to work fine, it is distributed "as is". Use at your own risk.
LDapper is a simple LDAP (Lightweight Directory Access Protocol) client for finding e-mail addresses. You can look up people by name and/or department. Once you have a list of people, you can copy/paste or drag addresses into a new e-mail message. Depending on your e-mail client, you may be able to automagically add them to a new message by selecting the "Mail To:" command in the LDAP menu or by clicking the e-mail button. Try it and see if it works. It does with Mail Drop. (Go figure... :-)
For more information on LDAP, see Innosoft's LDAP World:
<http://www3.innosoft.com/ldapworld/index.html>
and University of Michigan LDAP:
<http://www.umich.edu/~dirsvcs/ldap/index.html>
Special thanx go to One Click Systems, makers of ClickMail Central Directory (an LDAP server for the Macintosh) for their assistance as I added international character support to LDapper:
<http://www.oneclick.com/>
Directories
You will need to set up at least one directory before you can do a search. (This can be the "Internet Config Default" directory - see below.) Open up preferences and click the add (+) button. If you hold down the option key while clicking the add button, a copy of the current directory will be added. Then specify the directory's name (which can be whatever you want, but must be unique), the LDAP server's IP address, and an optional (but sometimes not so optional) search base. You can also specify an IP port if it is different from the normal LDAP port (389). Click the edit (pencil) or delete (trashcan) buttons to edit and delete directories. There will also be an directory that corresponds to the default Internet Config directory. You cannot edit or delete this directory within LDapper.
At Baylor, you will want to enter one or more of the following:
Search base: ou=Faculty and Staff, o=Baylor University, c=US
Note that Baylor runs two LDAP servers, one on the standard port 389, and one on port 390. Because the 390 server contains information that is not considered "public" information, e.g., home addresses and phone numbers, it is only accessable on the Baylor network. E-mail addresses are available on both servers so you can use the default port without any problems.
You can also specify some of the default attributes that LDapper uses. While editing the directory, click the "Attributes" tab. These attributes (and default values) include Last Name (sn), Full Name (cn), Department (ou), and E-mail Address (mail). You can also specify the value for the objectClass
attribute (person) used to restrict searches to people. Unless you know that you need to change these, you should leave these set to the defaults. To reset the values to their defaults, click the "Defaults" button. The attributes panel is where you specify the encoding to use for international characters such as ö or ñ. The default encoding is "No Encoding" (just plain MacRoman/ASCII characters). For many users this should be fine since most of the information will be in ASCII anyway. One major benefit of not encoding is that searches will be faster. If you know that you need to use international characters, you will probably want to use the UTF-8 (Unicode) encoding. UTF-8 is required for LDAPv3 but is commonly used in LDAPv2 systems (which is what LDapper supports). Note that in order to use UTF-8, you must have Apple's Text Encoding Converter extension installed on your Mac. LDapper will allow you to specify UTF-8 without TEC installed but will fall back to "No encoding". LDapper also supports ISO-Latin-1 and Mac-Latin-1 encodings. These use internal tables to convert characters so the Text Encoding Converter is not required (although TEC was used to generate the tables themselves). The last encoding T.61 is actually the
official encoding method for LDAPv2 but is not supported by LDapper and so the menu item is disabled.
Some information is only available if you identify yourself to the LDAP server. For example, the server may be set up to only allow people at your site to view home address and phone number information; anonymous users will not be able to retrieve these attributes. You can set your credentials by clicking the "Authentication" tab. Enter your identification (possibly your "distinguished name", e.g., "cn=Rocket Squirrel, o=Wossamotta University, c=US") and an optional password. If you leave the password field blank, LDapper will identify you but you will probably have the same access as if you were anonymous. Note that although you may be authenticated, you cannot use LDapper to change information on the server.
Searching
Select the New command in the File menu to open a new search window with initial settings as specified in Preferences. You can change several of the settings, e.g., the directory, types of searches, before doing a search.
To do a search, enter some text in the name and/or department field, then click the Find button (or select the Find command in the LDAP menu, or press return). Click the words "Last Name:" (or "Full Name") to toggle between last name (LDAP's sn) and full name (LDAP's cn) searches. The department is really organizational unit (LDAP's ou). You can choose the search types for names and departments with the popup menus in a search window. The choices are: is, is similar to, contains, starts with, ends with.
If the first character in the name field is an open parenthesis '(', LDapper will assume that that is a "real" LDAP search filter and will just pass it onto the the server. [I'm not going to try to explain search filters. You either know how to specify one or you don't. LDapper always does a subtree search - you cannot specify base-object or one-level searches.] Hold down the option key when clicking the search button to see the search filter that will be sent to the server.
You can specify the maximum number of responses you want to receive from the LDAP server. The default is 100. Set this to 0 to designate no limit (but you may run out of memory). Also note that there may be a limit set by the server. You can also specify how long to wait for a response before timing out. Set this to 0 to wait forever. (Maybe not such a good idea.) The default is 30 seconds. The default max hits and time limits are set in preferences but you can also change the values without changing the defaults in their corresponding fields in the search window.
There are a few other options that can be set before doing a search. The "Clear List Before New Search" checkbox specifies whether or not all of the addresses in the list are removed so that all of the entries in the list will be matches to the current search and not old matches. The "Discard Responses Without E-mail" checkbox specifies whether or not responses that are missing e-mail addresses are ignored. If this is not enabled, entries in the list without e-mail addresses will show "n/a" instead. You will not be able to include any of these (non-)addresses when performing a "mailto". The "Search For People Only" checkbox specifies whether or not LDapper should limit a search to only people, i.e., those entries with an objectClass value of "person". (This can be modified in preferences when editing a directory.) For example, if you do a search for people in a department that contains "Marketing", the server may return responses for the departments themselves. These three options are persistent and are saved to the preference file.
LDapper will connect to the server when you first do a search, but will not close the connection until the window is closed, a different directory is specified, the preferences are modified, or the number of seconds specified in the internal IDLEDISCONNECTSECONDS preference mentioned below have passed since the last search.
You can save the search criteria to a file by selecting the "Save Search Criteria" command in the File menu. Information saved in the file includes the current directory, last/full name search, type of name search (from the popup menu), the name to search for, type of department search, and the department to search for. Select the "Open Search Criteria..." command from the File menu to open the file. The search criteria will be applied to the frontmost search window. If there is not a search window open, a new one will be created first. Saving and opening files will use Navigation Services, if available. If you encounter problems with this, hold down the option key and select the commands to use the old style Standard File dialogs. Because Navigation Services is sometimes slow, there is a preference that will permanently disable it so you don't have to hold down the option key each time. Note that doing this may cause problems on newer versions of the OS that requires Navigations Services.
The Address List and Info Field
When you click the Find button, or select the Find command from the LDAP menu, a search query is sent to the server. As entries are added to the address list, you can cancel the operation by pressing cmd-period. If there are no matches to your search, or more matches than the "Max # Hits" preference, LDapper will let you know. The search requests only a minimal set of attributes for matching responses (name, email, and dept). As mentioned above, entries without an e-mail address will show "n/a" in the list. If an entry doesn't have a name (cn), but does have a department (ou),
then the list will show the department name. Entries without names or deparments will show "n/a". To remove entries from the list, select them, then hit delete or choose the Clear command from the Edit menu.
To specify how the address list is sorted, click in the address list's "Name" or "E-Mail" column header. You can change the width of the columns by clicking the line between the column headers and dragging. To switch between ascending and descending sorts, click the sort button above the list's scroll bar. LDapper will remember the way that the address list is sorted and the with of the columns between sessions.
Choose the "Show/Hide Info" menu to show/hide detailed information about the selected address. This information is not fetched until it is actually needed, in other words, when you select an entry in the list. Older versions of LDapper would always request the detailed info in the initial search which was slower and sometimes caused problems with some servers. If you switch directories or modify the current directory in preferences, LDapper will not fetch the info for any of the addresses that are already in the list although it will for addresses found in subsequent searches. The list of "full" attributes is stored in an internal resource in LDapper, but you can specify other attributes if you are familiar with ResEdit. (See below.)
You can modifiy the size of the address list and info field by clicking on the line between the two and dragging the mouse. The size is saved between sessions. (Sometimes, especially when zooming the window, the sizes of the list and field may jump unexpectedly. This is a known bug caused by the way LDapper handles sizing of the window. Just resize the list/field again.) If you ever need to reset the window, the address list, and info field, to their default positions, hold down the option key while opening a new window.
Copying/Dragging Addresses
Click one or more entries in the address list to select them. Then you can copy/paste or drag them to your e-mail application. Entries without e-mail addresses will not be included. Different e-mail applications handle copying (and dragging) of addresses differently. You will need to experiment with some settings to see what works best with your e-mail application.
If the "Separate With Commas" preference is enabled, addresses will be separated with commas, e.g.,
rocky@wossamotta.edu,bullwinkle@wossamotta.edu
If it is disabled they will be separated with carriage returns, e.g.,
rocky@wossamotta.edu
bullwinkle@wossamotta.edu
If the "Include Personal Names" preference is enabled, then you'll get
"Rocket J. Squirrel" <rocky@wossamotta.edu>,"Bullwinkle J. Moose" <bullwinkle@wossamotta.edu>
or
"Rocket J. Squirrel" <rocky@wossamotta.edu>
"Bullwinkle J. Moose" <bullwinkle@wossamotta.edu>
You can export addresses to a text files by choosing the "Export Addresses" menu. The exported address file can be imported into your Mail Drop address book or group if you have the "Text Addresses" plug-in installed.
"Mail To:"
LDapper can automagically create a new e-mail message pre-addressed with selected addresses if your e-mail application supports this. This works the same way as if you had clicked on a "mailto:" URL in a web page so any program that can be set up as a mailto URL helper should work. You first must specify which e-mail application you want to use in the preferences dialog. (The default application is Mail Drop...) Note that both the application's creator, e.g., 'MDrp' for Mail Drop, and an alias to the application is saved in the preference file. What this means is that normally LDapper will use the alias to get the application, but if for some reason that doesn't work, it will try to convert the application's creator back into the application, and it may find a different copy. If the "Use Internet Config" preference is enabled, LDapper will simply pass off the address to IC and let it handle it although if you don't have an e-mail helper set, nothing will happen. Select one or more entries in the address list, then click the "Mail To:" button or select the "Mail To:" command in the LDAP menu to send the address(es) to your e-mail application. Double-clicking an address or pressing return/enter while the address list is active will do the same thing.
Note that sending addresses to your e-mail application in this manner will not include personal names. If you want personal names, you must use copy/paste or drag and drop instead. Also, some applications require a trailing null at the end of each address, while some others will only work if there isn't one there. There is a preference to include this or not. Try an address and if it doesn't seem to work, toggle this preference. Finally, there is no way to include multiple addresses in a single mailto so LDapper must send a separate mailto for each address. Most applications create a new message for each mailto. Some applications, including Mail Drop, will create a new message (if the front window is not already a new message) only for the first one, and subsequent mailtos will be added to that message. If the latter is what you prefer, you should let the vendor or developer of your e-mail application know.
Checking for the Latest Version
You can now have LDapper check to see if you are running the latest version. Open the "About LDapper" window and click the "Latest Version?" button. This will send a query to a remote server and get information about the latest version. (A dialog will ask you to confirm the query. If you are concerned about privacy issues, please note that no information is being sent to the server. But you can always cancel the request, just in case.) If you are curious, this is simply sending a http request to a web server and parsing the results. Afterwards, URLs where you can get more information about LDapper as well as download the latest version will be displayed in the window. Click the URLs to launch a browser to go to the web page or download the files. If the "Use Internet Config" option is enabled, it will use that, otherwise it will search for and use Netscape or Internet Explorer in that order. Hold down the shift key and you can drag the URLs to the desktop or some other program.
Internal Defaults
Lab managers can can specify initial defaults for various preferences. These are stored inside of LDapper in a 'TEXT' resource (ID 10000). Because the LDapper Preferences file is really a text file, you can copy and paste the entries into the TEXT resource. The order of the pref entries is irrelevant. Important: There must be a return after the last entry in the TEXT resource.
LDapper's default preferences are:
Admin prefs not written to pref file
CANSAVEPREFS=T
DONTLAUNCHASHARE=T
DEFAULTBROWSER=MOSS
IDLEDISCONNECTSECONDS=120
Normal prefs
FULLDIRECTORY=see below
CURDIRECTORY=1
MAXHITS=100
TIMELIMIT=30
CLEARLIST=T
DISCARDNONEMAIL=T
DEFAULTNAMESEARCH=3
DEFAULTDEPTSEARCH=4
EMAILAPP=MDrp
EMAILAPPALIAS=see below
USEINTERNETCONFIG=F
SEPARATEWITHCOMMAS=T
INCLUDEPERSONALNAMES=T
LASTNAMESEARCH=T
SHOWINFO=F
PEOPLEONLY=T
SORTBYNAME=T
ASCENDINGORDER=T
NAMECOLUMNWIDTH=180
USENAVSERVICES=T
DONTCONFIRMQUERY=F
TRAILINGNULL=F
LDAPWINDOWBOUNDS=see below
LDAPWINDOWSPLIT=see below
UPDATEHOST=see below
UPDATEREQUEST=see below
UPDATEREQUESTPPC=see below
You only need to add entries to the TEXT resource if you want something different than the above defaults. Add the CANSAVEPREFS pref and set it to F for lab environments but make sure you add at least one DIRECTORY entry in the TEXT resource.
Boolean (true/false) values should be either T or F. Integer values are just the number. The default searches types are:
1 - is
2 - is similar to
3 - contains
4 - starts with
5 - ends with
No directory is specified by default, but the entry looks like:
Note that the line break after the searchbase and mailAttr is only to make this readable. The FULLDIRECTORY entry must be on one line. Older versions of LDapper used a shortened version of this (DIRECTORY) that did not include the attributes or authentication info. This is no longer supported.
It is probably easiest to set up directories in the preferences dialog and then copy/paste them from the prefs file into the 'TEXT' resource. You can leave the ID and password blank. The password is encrypted and encoded so you can't type it in beforehand anyway.
The EMAILAPPALIAS is an alias record ("hexified") of the chosen e-mail helper application. If missing, or if the alias cannot be resolved, LDapper will search the hard disks for the application whose singature is specified in EMAILAPP.
LDapper will sometimes search the Mac's hard disks for an application, e.g., the e-mail application or a web browser. Normally, mounted AppleShare volumes are ignored so that LDapper won't try to launch (and more importantly, save an alias to) a program that resides on a remote server. To have LDapper include AppleShare volumes, add a DONTLAUNCHASHARE=F entry.
As mentioned above, LDapper also can launch a web browser after checking for a newer version. If the "Use Internet Config" option is enabled, LDapper will just use it. If not, it will search for and use Netscape Navigator and Microsoft Internet Explorer in that order. If you want to force it to use IE or have a different browser, add a DEFAULTBROWSER=???? entry. Replace the ?'s with the signature of your browser (MSIE for Explorer).
The IDLEDISCONNECTSECONDS specifies how long (in seconds) that LDapper will keep the connection to the server open after doing the last search. If you are doing several searches, it is more efficient to use the same connection rather than open and close a new connection for each search. This setting will avoid accidentally leaving connections open for extended periods of time. The default is 120 seconds (2 minutes).
LDapper will save the current search window size and position as well as the location of the "splitter" between the address list and info field. If you want to use something different than the default, e.g., because you have a larger monitor, set the window how you want it and copy the LDAPWINDOWBOUNDS and LDAPWINDOWSPLIT preferences to the internal prefs. (Do not modify the WIND or PPob resources.) Of course, this won't be useful unless the CANSAVEPREFS value is F.
When LDapper checks for a new version (from the About window) the remote server may return a new host and http request to be used the next time, especially if the "update info" web page is moved or renamed. This is stored as the UPDATEHOST and UPDATEREQUEST[PPC] prefs. If the CANSAVEPREFS value is F, then this won't be saved which may cause problems. If you notice that there is a new host/request preference, or if you want to use a different host/reuqest for some reason, you can copy the prefs to the internal prefs.
LDapper no longer requests all available attributes for the Info field but instead uses a specific list stored internally in STR# resource 5000. The default attributes are:
cn objectClass
ou onVacation
mail organizationalStatus
sn otherMailbox
affiliationCode pager
businessCategory personalTitle
classStanding physicalDeliveryOfficeName
description pid
destinationIndicator postalAddress
drink postalCode
facsimileTelephoneNumber postOfficeBox
givenname preferredDeliveryMethod
homePhone registeredAddress
homePostalAddress roomNumber
initials secretary
internationalISDNNumber seeAlso
krbName st
l streetAddress
labeledURI telephoneNumber
labeledURL title
mailPreferenceOption uid
memberOfGroup universityID
mobile userClass
multiLineDescription userPassword
notice vacationMessage
These cannot be modified within LDapper, so if you wish to include additional attributes, or possibly want a reduced list, you can use ResEdit to modify this resource. A better solution would be to create a file called "LDapper Attributes" that contains a STR# 5000 resource with the attributes
you want to use and store the file in either the preferences folder or the same folder as LDapper. Note that these attributes are global and not directory specific.
Release Notes
The release notes have been moved to a separate document because when they are included here, the
file is too large to open with SimpleText.
If you have any questions, comments, (constructive) criticism, or bug reports, you can contact me at the address(es) below.
-cb
Carl_Bell@baylor.edu
Carl Bell's Web Page <http://www.baylor.edu/~Carl_Bell/>
Stuff I've Written <http://www.baylor.edu/~Carl_Bell/stuff.html>
Snail Mail:
Carl W. Bell
Information Technology Center
Baylor University
P.O. Box 97268
Waco, TX 76798-7268
Phone:
(254) 710-4065
Baylor's Fine Print:
This software, data and/or documentation contain trade secrets and confidential information which are proprietary to Baylor University. Their use or disclosure in whole or in part without the express written permission of Baylor University is prohibited.
This software, data and/or documentation are also unpublished works protected under the copyright laws of the United States of America. If these works become published, the following notice shall apply:
The name of Baylor University may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE, DATA AND/OR DOCUMENTATION ARE PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
When permission has been granted to make copies of this software, data and/or documentation, the above notices must be retained on all copies.
Permission is hereby granted for non-commercial use and distribution of LDapper.
UMich LDAP SDK's Fine Print
Copyright (c) 1990 Regents of the University of Michigan.
All rights reserved.
Redistribution and use in source and binary forms are permitted provided
that this notice is preserved and that due credit is given to the University
of Michigan at Ann Arbor. The name of the University may not be used to
endorse or promote products derived from this software without specific
prior written permission. This software is provided ``as is'' without
